What is best way to convey an "interface" for a DXL module?

I know C and DXL have some features in common but the "extern" reserved word is not one of them.

Unfortunately DXL does not have a means of declaring functions, constants, or variables as either public or private.

Encapsulation is nice to have for good software engineering practices. Has anyone found a good means support the "spirit" of this with DXL?

If a functional modules are are stacked up in separate DXL source files like this:
  

#include "package1.dxl"
#include "package2.dxl"
#include "package3.dxl"
#include "package4.dxl"

 


What would be a good means of indicating to others:

 

 

 "Here are the parts of this module (e.g., package2.dxl) that are meant for public use (e.g., the interface)"


Options are:
1) Indicate intent in comments
2) A "header file" of forward declared functions could be made to indicate the intended function interface.
3) Is there some "header" technique that could be applied to variables (most typically variables used as constants). In the C programming language there was a "extern" storage specifier that said "this identifier exists as this type, but the storage is elsewhere". If the storage is not defined somewhere, you'll get a unresolved symbol error at link time.

Is there anything like "extern" available for DXL?

The general issue is if I have a module with 10 constants and 20 functions and 1 constant is desired for non-local use and 5 functions are desired for non-local use, is there a clean way to indicate the DXL author's intent?

PS - Since in most circumstances I'd like to expose "constants", maybe to only alternative is to have functions return the constant's value. For example:

 

 

 

  

const string INTERNAL_CONSTANT = "Internal Constant Value";
string EXPOSED_CONSTANT() {
    return INTERNAL_CONSTANT;
}



An #include header file could then contain:



 

 

 

  

string EXPOSED_CONSTANT();



For the compiler, I know all that is necessary is that 1 (and only 1) definition of a constant must lexically appear in a series if #include files for a symbol to resolve. My concern is for the user.

Is this the only option to define constants in one place and use them in others?



 

 

 

SystemAdmin - Wed Jun 30 14:15:53 EDT 2010

Re: What is best way to convey an "interface" for a DXL module?
Mathias Mamsch - Wed Jun 30 14:35:23 EDT 2010

DXL does by default not provide private namespaces or stuff like that.

I can offer you three methods, that you can use to make the interface clear to other developers:

a) Use Doxygen (see earlier post or example in the dxl standard library) to document your code (generates HTML help page or compiled html -> CHM). Document only the public interface!

b) Mark private functions with an underscore _ at the end of the name. That is like a convention in DOORS.

c) encrypt the private part of your include files, deliver the public part unencrypted.

I guess most of the time it is convenient only to add the underscores to the name and trust people that they will only use those functions.

Regards, Mathias
Mathias Mamsch, IT-QBase GmbH, Consultant for Requirement Engineering and D00RS

Re: What is best way to convey an "interface" for a DXL module?
SystemAdmin - Wed Jun 30 16:42:34 EDT 2010

Mathias Mamsch - Wed Jun 30 14:35:23 EDT 2010
DXL does by default not provide private namespaces or stuff like that.

I can offer you three methods, that you can use to make the interface clear to other developers:

a) Use Doxygen (see earlier post or example in the dxl standard library) to document your code (generates HTML help page or compiled html -> CHM). Document only the public interface!

b) Mark private functions with an underscore _ at the end of the name. That is like a convention in DOORS.

c) encrypt the private part of your include files, deliver the public part unencrypted.

I guess most of the time it is convenient only to add the underscores to the name and trust people that they will only use those functions.

Regards, Mathias

Mathias Mamsch, IT-QBase GmbH, Consultant for Requirement Engineering and D00RS

Thanks. I wasn't expecting any miracles but you never know. I downloaded Doxygen (looks similar to Javadoc).

If the underscore suffix '_' for "internals" is conventional, I may as well go with it.

I'll be sure not to any internal identifier called addr_ however :)

Re: What is best way to convey an "interface" for a DXL module?
Mathias Mamsch - Wed Jun 30 16:47:56 EDT 2010

SystemAdmin - Wed Jun 30 16:42:34 EDT 2010
Thanks. I wasn't expecting any miracles but you never know. I downloaded Doxygen (looks similar to Javadoc).

If the underscore suffix '_' for "internals" is conventional, I may as well go with it.

I'll be sure not to any internal identifier called addr_ however :)

Just a tip: If you use doxygen to generate your documentation you would need to replace the .inc file ending in the doxygen.exe file, since it is hardcoded to be reserved for php. Therefore .inc files are not properly recognized by doxygen.

Find some details and an example in an earlier post here (search for doxygen) or take a look at the DXL standard library (sourceforge) for the patched doxygen and some examples.

Regards, Mathias
Mathias Mamsch, IT-QBase GmbH, Consultant for Requirement Engineering and D00RS

Re: What is best way to convey an "interface" for a DXL module?
llandale - Wed Jun 30 17:04:18 EDT 2010

Have a massive library that is just about to be put in public use about the company. I had adopted a convention that functions in the library start with "f", which functions in the library intended just for other library functions and not intended for direct general use start with "fl". Have a similar naming convention for library variables and constants.

Since things are about to change and my functions may be merged with other sector's, yet I retain control, I'll need a better naming convention, one that indicates which Sector 'owns' the function, which will discourage identical function name conflicts.

You can indeed embed functions inside other functions, but these embedded functions cannot use variables defined in the parent function. Odd, very odd; and that makes embedding functions pretty useless.

  • Louie